Visual IRC 2.0 DDE Interface
Jesse McGrew
September 8, 2002

As a client
===========

ViRC's /dde command combines the features of poking data into an item,
executing a macro, and reading an item's value. It can also execute a macro
and then read an item's value in the same operation.

Poking data:
  /dde <service> <topic> "<item>" <data>

Executing a macro:
  /dde <service> <topic> "" <macro>

Reading an item's value:
  $dde(<service> <topic> "<item>")

Executing and then reading:
  $dde(<service> <topic> "<item>" <macro>)

As a server
===========

ViRC provides two services with DDE: executing a single command and evaluating
text.

Executing a single command
--------------------------

Open a connection to the service "ViRC" and the topic "IRC_Execute". Send the
command you wish to execute as a macro (XTYP_EXECUTE).

Note that the command will not be evaluated before it is run. If you want it
to be evaluated, use "Eval <your command here>".

Visual Basic:
  txDDE.LinkTopic = "ViRC|IRC_Execute"
  txDDE.LinkMode = 2
  txDDE.LinkExecute "Join #quake"

Delphi:
  procedure ViRC_Execute(const x: string);
  var
    ddeC: TDDEClientConv;
  begin
    ddeC := TDDEClientConv.Create(nil);
    if (ddeC.SetLink('VIRC', 'IRC_Execute')) then
       ddeC.ExecuteMacro(PChar(x), False);
    ddeC.Free;
  end;

For compatibility with other IRC clients, you can also send a command
via XTYP_POKE, using the topic name "command" and the item name
"IRC_Command". In this case, the command will be evaluated before being
executed. It may also contain line breaks to execute more than one command.

Delphi:
  procedure ViRC_ExecuteBlock(Lines: TStrings);
  var
    ddeC: TDDEClientConv;
  begin
    ddeC := TDDEClientConv.Create(nil);
    if (ddeC.SetLink('VIRC', 'command')) then
       ddeC.PokeDataLines('IRC_Command', Lines);
    ddeC.Free;
  end;

Evaluating text
---------------

Open a connection to the service "ViRC" and the topic "DDE". Send the text you
wish to parse as a macro, then read the item "IRC_ParseVars" to get the result.

Visual Basic:
  txDDE.LinkTopic = "ViRC|DDE"
  txDDE.LinkItem = "IRC_ParseVars"
  txDDE.LinkMode = 1
  txDDE.LinkExecute "My nickname is $N."

Delphi:
  function ViRC97_ParseString(x: string): string;
  var
    ddeC: TDDEClientConv;
    ddeI: TDDEClientItem;
  begin
    ddeC := TDDEClientConv.Create(nil);
    ddeI := TDDEClientItem.Create(nil);
    ddeI.DDEConv := ddeC;
    if (ddeC.SetLink('ViRC', 'DDE')) then
    begin
      ddeI.DdeItem := 'IRC_ParseVars';
      ddeC.ExecuteMacro(PChar(x), False);
      Result := ddeI.Text;
    end;
    ddeC.Free;
    ddeI.Free;
  end;